---
title: Brightness
description: A library that provides access to an API for getting and setting the screen brightness.
sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-52/packages/expo-brightness'
packageName: 'expo-brightness'
iconUrl: '/static/images/packages/expo-brightness.png'
platforms: ['android', 'ios']
---

import APISection from '~/components/plugins/APISection';
import { APIInstallSection } from '~/components/plugins/InstallSection';
import { AndroidPermissions } from '~/components/plugins/permissions';
import { ConfigReactNative } from '~/ui/components/ConfigSection';
import { SnackInline } from '~/ui/components/Snippet';

An API to get and set screen brightness.

On Android, there is a global system-wide brightness setting, and each app has its own brightness setting that can optionally override the global setting. It is possible to set either of these values with this API. On iOS, the system brightness setting cannot be changed programmatically; instead, any changes to the screen brightness will persist until the device is locked or powered off.

## Installation

<APIInstallSection />

## Configuration

<ConfigReactNative>

If you're not using Continuous Native Generation ([CNG](/workflow/continuous-native-generation/)) or you're using a native **android** project manually, then you need to add the `android.permission.WRITE_SETTINGS` permission to the **AndroidManifest.xml** file:

```xml android/app/src/main/AndroidManifest.xml
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
```

</ConfigReactNative>

## Usage

<SnackInline label='Basic Brightness Usage' dependencies={['expo-brightness']}>

```jsx
import { useEffect } from 'react';
import { StyleSheet, View, Text } from 'react-native';
import * as Brightness from 'expo-brightness';

export default function App() {
  useEffect(() => {
    (async () => {
      const { status } = await Brightness.requestPermissionsAsync();
      if (status === 'granted') {
        Brightness.setSystemBrightnessAsync(1);
      }
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>Brightness Module Example</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```

</SnackInline>

## API

```js
import * as Brightness from 'expo-brightness';
```

<APISection packageName="expo-brightness" apiName="Brightness" />

## Error codes

### `ERR_BRIGHTNESS`

An error occurred when getting or setting the app brightness.

### `ERR_BRIGHTNESS_MODE`

An error occurred when getting or setting the system brightness mode. See the `nativeError` property of the thrown error for more information.

### `ERR_BRIGHTNESS_PERMISSIONS_DENIED`

An attempt to set the system brightness was made without the proper permissions from the user. The user did not grant `SYSTEM_BRIGHTNESS` permissions.

### `ERR_BRIGHTNESS_SYSTEM`

An error occurred when getting or setting the system brightness.

### `ERR_INVALID_ARGUMENT`

An invalid argument was passed. Only `BrightnessMode.MANUAL` or `BrightnessMode.AUTOMATIC` are allowed.

## Permissions

### Android

You must add the following permissions to your **app.json** inside the [`expo.android.permissions`](../config/app/#permissions) array.

<AndroidPermissions permissions={['WRITE_SETTINGS']} />

### iOS

_No permissions required_.
